home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
FishMarket 1.0
/
FishMarket v1.0.iso
/
fishies
/
526-550
/
disk_539
/
simplerexx
/
simplerexx.doc
< prev
next >
Wrap
Text File
|
1992-05-06
|
7KB
|
158 lines
SimpleRexx
by
Michael Sinz
A Simplified Interface into the world of ARexx
ARexx, ARexx, ARexx. 2.0 has ARexx. So, why and how do I
support ARexx?
The "Why?" has been answered elsewhere and that is not what this
article is about. Let it suffice that you should support ARexx
within your application. It is a standard that Commodore is
pushing and we hope that all new applications will have ARexx
support.
As to the "How?", that is what this article is about. We
understand that your existing software may not currently support
ARexx and that some of you may never even have looked at what is
needed to support ARexx. New applications can be designed with
ARexx support in mind and, with the advent of the AppShell by
David Junod, the work involved to support ARexx is nothing more
than what is needed to support the features within you
application. However, existing code may not move into the
AppShell to easily and you may wish to do a minor upgrade to
your application to support ARexx.
SimpleRexx is a set of routines that handle the low-level ARexx
work for you in such a way as to have your application work with
or without ARexx on the target system. The goal of SimpleRexx is
to make adding at least the minimum level of ARexx support to an
application a trivial task.
Working with ARexx
REXX is, at its heart, a string processing language. Most
everything that happens in REXX is in the form of a string; even
numbers are passed as ASCII representations in most situations.
The Amiga implementation of REXX, known as ARexx, and is part of
Release 2.0 of AmigaDOS. ARexx has a very complete
implementation of the REXX language plus the ability to send and
receive control messages from "outside" sources. ARexx the can
operate on them in synchronous fashion. The messages contain
text strings that are then interpreted by ARexx as REXX commands
or by the "outside" source (the Application) as its commands.
An application that "supports ARexx" is one that can receive and
send ARexx messages. The messages are, like the REXX language,
string based and contain the command string of the operation
wanted.
To make this even more interesting, there are ways to send and
receive data from ARexx. The data can come in the message itself
or via the ARexx RVI (Rexx Variable Interface). In either case
data can be transferred to and from ARexx. A complete ARexx
supporting application would need to be able to send data to a
requesting ARexx program/script and get data from that program.
The following code shows how to use the ARexx support library to
send and receive ARexx messages. It also is a "wrapper" around
these functions to provide a simplified interface to ARexx to
help promote and simplify the idea of adding ARexx support to
your existing applications.
SimpleRexxExample.c is a very simple example of the use of the
calls in SimpleRexx. The test.rexx script is an example script
to try running while SimpleRexxExample is running. It will send
commands to SimpleRexxExample in order to control it.
test.results is the output of test.rexx.
Overview of Functions
The source to SimpleRexx is a single file. It is SimpleRexx.c.
The header file to that contains the type definitions and
prototypes for the functions is in the file SimpleRexx.h.
Functions that are "available" via SimpleRexx are used as
follows:
rexx_handle=InitARexx(AppBaseName,Extension)
This initializes a SimpleRexx context. The rexx_handle
is much like a file handle in that it will be used in
all other calls that make use of this SimpleRexx
context. Since all SimpleRexx calls correctly check
the rexx_handle before doing work, you do not need to
check the return result of this call. If ARexx is not
available on your system, SimpleRexx will just not do
anything.
port_name=ARexxName(rexx_handle)
This function returns a pointer to the name of the
ARexx port for your context. The name is based on the
AppBaseName plus an invocation number such that
multiple copies of an application can run at the same
time. If you have no ARexx port, it returns NULL.
sigmask=ARexxSignal(rexx_handle)
This function returns the signal bit mask that is
needed for the port that is part of your context. This
should be combined with other signal masks to produce
the argument to the Wait() call. This returns NULL if
there is no signal mask.
rmsg=GetARexxMsg(rexx_handle)
This function returns the next Rexx message that is
waiting. rmsg==NULL if there is no message or ARexx is
not around. rmsg==REXX_RETURN_ERROR if a message sent
to ARexx via SendARexxMsg() returns an error.
ReplyARexxMsg(rexx_handle,rmsg,result,error)
This function replies the ARexx message gotten via
GetARexxMsg(). The "result" is a pointer to a result
string that is returned via OPTIONS RESULTS in the
RESULT ARexx variable. If you have no result, set this
to NULL. Error is the error severity level. If this
is 0, the result string will be returned, if this is
non-zero, the error level will be returned in RC.
worked=SendARexxMsg(rexx_handle,string,StringFileFlag)
This function sends the string to ARexx. It sets the
default host to the context and sets the RXFB_STRING
bit in the message if the "StringFileFlag" is set.
This routine returns FALSE if the message was not sent
for some reason.
worked=SetARexxLastError(rexx_handle,rmsg,ErrorString)
This function uses the RVI (Rexx Variable Interface) to
set a variable named <AppBaseName>.LASTERROR to the
ErrorString. This is where the "error" message should
go if there is an error. This function returns FALSE
if this fails for any reason.
FreeARexx(rexx_handle)
This closes a SimpleRexx context. The rexx_handle is
one that was gotten from InitARexx(). The routine is
fully error checked so that you can pass it a NULL and
it will do nothing. This is useful if you want to
just blindly use the rexx_handle.